Auto-generate experimental warnings and usage docs for typekits from library metadata by Copilot · Pull Request #9564 · microsoft/typespec

Copilot · 2026-02-02T23:57:53Z

Original prompt

This section details on the original issue you should resolve

<issue_title>[Bug]: Http typekits are not exposed and documentation is missing info on how to use</issue_title>
<issue_description>### Describe the bug

I had to add
import "@typespec/http/experimental/typekit";
To make them work in a non Alloy environment. Otherwise typescript doesn't see merged typekit declaration and missing all http typekits.

This should be either documented or exposed and working with http module import.

Reproduction
import { getHttpOperation } from "@typespec/http";
import { $ } from "@typespec/compiler/typekit";
// import "@typespec/http/experimental/typekit"; // uncomment to make this work


const [httpOperation] = getHttpOperation(program, operation);
$(program).httpOperation.flattenResponses(httpOperation);
Checklist

Follow our Code of Conduct

Check that there isn't already an issue that request the same bug to avoid creating a duplicate.

Check that this is a concrete bug. For Q&A open a GitHub Discussion.

The provided reproduction is a minimal reproducible example of the bug.</issue_description>

<agent_instructions>Indicate in the documentation for http typekits how to import the typekits. Also ensure thatr the documentation indicates that the typekits are experimental and may have breaking changes without notice.</agent_instructions>

Comments on the Issue (you are @copilot in this section)
@markcowl @artsiommiksiuk The typekit for http is currently experimental, the API surface area is volatile, and it is not documented so that customers do not inadvertently take a dependency on it without understanding the risks. This is why it is both exported as experimental and undocumented.
If the ask is to get the API to move the API from experimental to part of the public exports, that is ongoing work, but we cna use this issue to track it, if you like</comment_new>

Fixes [Bug]: Http typekits are not exposed and documentation is missing info on how to use #8575

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

…mentation Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

markcowl · 2026-02-24T02:01:22Z

@copilot please pull the latest from the main branch and fix any issues with website build

Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

This reverts commit f6c5749.

Copilot · 2026-02-24T02:12:43Z

@copilot please pull the latest from the main branch and fix any issues with website build

Done. I've successfully merged the latest main branch (commit aa2b623). The website build completes without errors, and all astro checks pass with 0 errors, 0 warnings, and 0 hints.

The HTTP typekits documentation now includes:

✅ Experimental warning banner
✅ Clear import instructions
✅ Practical usage example

The documentation is fully compatible with the latest main branch changes.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

telemetry.astro.build
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js check --minimumFailingSeverity hint (dns block)
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build sh s/.b�� ../../website/src/content/docs/d--output-dir dotnet p/bin/sh perimental gen-esh bash (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

markcowl · 2026-03-03T03:31:17Z

@copilot This problem cannot be solved by editing a static documentation web page, because the reference documentation is automatically generated from the source code using tspd which is a documentation generation package built in this repo. Please use any appropriate functionality in tspd to embed the new information into code comments in the typescript source for the http typekit, or add some functionality to tspd to allow you to add front matter for a typekit.

markcowl · 2026-03-03T03:35:17Z

@copilot, also you need to merge in the latest changes from main. You should do this whenever you make an update to the code in your branch.

…umentation Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Copilot · 2026-03-03T03:45:27Z

@copilot This problem cannot be solved by editing a static documentation web page, because the reference documentation is automatically generated from the source code using tspd wh...

Done (commit 7b6e19e). I've modified tspd to automatically detect @experimental tags in typekit interfaces and generate experimental warnings and usage documentation.

Changes made:

tspd enhancement: Added detection of @experimental JSDoc tags in typekit interfaces
Auto-generated warnings: Experimental typekits now automatically include a caution banner
Library-specific usage examples:
- HTTP typekits show how to import @typespec/http/experimental/typekit
- Compiler typekits show generic typekit usage patterns

The documentation is now auto-generated from source code comments, so future updates will automatically reflect changes to the experimental status and don't require manual documentation edits.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

telemetry.astro.build
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build api-extractor pec/�� ebsite/src/conte--llmstxt --verbose /.bin/node import @typespecnode bash tools/pnpm/10.23generate-scenarios-summary node tobu�� build.json gen-extern-signature /.bin/sh --no-emit sh tobuf/reference sh (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

markcowl · 2026-03-03T03:47:06Z

@copilot also you need to merge in the latest changes from main. You should do this whenever you make an update to the code in your branch.

Copilot · 2026-03-03T03:48:43Z

@copilot, also you need to merge in the latest changes from main. You should do this whenever you make an update to the code in your branch.

Done (commit 27e2db9). I've merged the latest changes from main branch into the PR branch. The merge completed successfully with 51 commits from main integrated.

markcowl

@copilot please pull the latest from main, fix the items in this review and ensure that all changed files are properly formatted using pnpm format

markcowl · 2026-03-05T00:32:20Z

packages/tspd/src/ref-doc/components/typekits-file.tsx

+  // Generate import statement based on package
+  let importStatement: string;
+  if (isHttpPackage && typekit.isExperimental) {
+    importStatement = `import "@typespec/http/experimental/typekit";`;


this pattern is followed for experimental packages, I feel like we can construct this from the package name and the fact that it is experimental, without having specific if statements for specific packages embedded in the code.

packages/tspd/src/ref-doc/components/typekits-file.tsx

website/src/content/docs/docs/standard-library/reference/typekits.mdx

…r typekits Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Copilot · 2026-03-05T00:49:14Z

@copilot please pull the latest from main, fix the items in this review and ensure that all changed files are properly formatted using pnpm format

Done (commit 843912c). I've addressed all review feedback:

Removed package-specific if statements: Import path is now constructed generically as ${packageName}/experimental/typekit for experimental packages
Skip usage for compiler: Compiler typekits now show only the experimental warning (no usage instructions since it's self-referential)
Latest main merged: Successfully merged latest changes from main branch
Regenerated all docs: Both HTTP and compiler typekit documentation regenerated
Validation passed: Both pnpm format and pnpm cspell pass with no issues

Result:

HTTP typekits: Shows experimental warning + usage instructions with import "@typespec/http/experimental/typekit";
Compiler typekits: Shows only experimental warning (no import instructions)

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

telemetry.astro.build
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build sh k/ty�� ebsite/src/conte--llmstxt dotnet .2_tmp_4070/node../../website/src/content/docs/docs/emitters/openapi3/reference --no-emit ture /.bin/sh node sion�� rs && pnpm build:src tsconfig.build.json modules/.bin/sh ld.json && pnpm node ps rsioning/referendoc node (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

packages/tspd/src/ref-doc/components/typekits-file.tsx

Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Copilot · 2026-03-05T21:35:34Z

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

telemetry.astro.build
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build -data-downloader. s/.b�� utput-dir ../../--llmstxt sh _modules/pnpm/dist/node-gyp-bin/node import @typespecnode sh s/.bin/sh node /nod�� es && pnpm build:lib && vite bui--typekits sh pec/node_modules/.bin/sh ld.json && pnpm node l/reference .2_tmp_3958/nodedoc node (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

markcowl

@copilot You should be able to simplify the logic in typekits-file.tsx so that more of the usage text is shared between different kinds of typekits

packages/tspd/src/ref-doc/components/typekits-file.tsx

…s and usage docs Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Copilot · 2026-03-05T21:56:41Z

@copilot You should be able to simplify the logic in typekits-file.tsx so that more of the usage text is shared between different kinds of typekits

Done (commit eeb575d). Refactored the logic to eliminate duplication:

Experimental Aside is now conditionally rendered only when typekit.isExperimental
Usage instructions are shared and shown for all packages (compiler and non-compiler) with conditional content
Registration import (import "${packageName}/experimental/typekit";) only shown for experimental non-compiler packages
The explanation about side effects only appears when the registration import is shown

The logic is now much simpler with less duplication between compiler and non-compiler cases.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

telemetry.astro.build
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build sh pec/�� utput-dir ../../--llmstxt sh pec/node_modules../../website/src/content/docs/docs/emitters/openapi3/reference pm run lint-typenode sh sh node pec/�� -p tsconfig.build.json .2_tmp_3923/node_modules/pnpm/dist/node-gyp-bin/sh . son st/node-gyp-bin/doc node (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

markcowl · 2026-03-09T20:06:48Z

@copilot Pull in the latest from main and fis the formatting of any changed files as needed (pnpm format)

…ilot/fix-http-typekits-documentation

Copilot · 2026-03-09T20:17:25Z

@copilot Pull in the latest from main and fis the formatting of any changed files as needed (pnpm format)

Done (commit a1b68fe). Merged the latest from main branch and ran pnpm format. All formatting is now up to date.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

telemetry.astro.build
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build node s/.b�� sc -p ./tsconfig--llmstxt node de_modules/pnpm/dist/node-gyp-bin/node import @typespecnode tsconfig.build.j/home/REDACTED/work/typespec/typespec/packages/http-specs/node_modules�� n-schema/referengenerate-scenarios-summary sh tobu�� astro check --minimumFailingSeverity hint && ast--filter node /.bin/sh lint-typespec-lish node tobuf/reference sh (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

markcowl · 2026-03-09T23:14:02Z

packages/tspd/src/ref-doc/components/typekits-file.tsx

+        import { Badge${typekit.isExperimental ? ", Aside" : ""} } from '@astrojs/starlight/components';
        `}
        </>
+        {typekit.isExperimental && (


This is still too complex and difficult to read. It should be possible to simplify the logic if the text of the pre-import and post-import documentation is conditional, instead of making large conditional code blocks.

Done (commit 4717332). Simplified the logic by extracting conditional text to variables (registrationImport, typekitImport, sideEffectsExplanation). The code is now much easier to read with minimal conditional blocks and clearer intent.

Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Copilot · 2026-03-09T23:29:25Z

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

telemetry.astro.build
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build sh k/ty�� ebsite/src/content/docs/docs/libraries/openapi/reference sh e . ture dist/node-gyp-bis,\\,/,g sh /nod�� tspd --enable-experimental gen-e--typekits dotnet .2_tmp_4092_0/node_modules/pnpm/dist/node-gyp-bin/sh r --no-emit l/reference k/typespec/typesdoc node (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Initial plan

ecd4435

Copilot AI assigned Copilot and markcowl Feb 2, 2026

Copilot started work on behalf of markcowl February 2, 2026 23:58 View session

Add usage instructions and experimental warning to HTTP typekits docu…

b002ac5

…mentation Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

microsoft-github-policy-service bot added the meta:website TypeSpec.io updates label Feb 3, 2026

Copilot AI changed the title ~~[WIP] Fix missing documentation for Http typekits~~ Document HTTP typekits import and experimental status Feb 3, 2026

Copilot AI requested a review from markcowl February 3, 2026 00:03

Copilot finished work on behalf of markcowl February 3, 2026 00:03

Copilot started work on behalf of markcowl February 24, 2026 02:01 View session

Copilot AI and others added 3 commits February 24, 2026 02:03

Merge latest main to fix website build issues

0e0dc1e

Merge latest main to fix website build issues

f6c5749

Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Revert "Merge latest main to fix website build issues"

aa2b623

This reverts commit f6c5749.

Copilot finished work on behalf of markcowl February 24, 2026 02:13

Copilot started work on behalf of markcowl March 3, 2026 03:31 View session

Add experimental warning and usage docs to auto-generated typekit doc…

7b6e19e

…umentation Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

microsoft-github-policy-service bot added the tspd Issues for the tspd tool label Mar 3, 2026

Copilot AI changed the title ~~Document HTTP typekits import and experimental status~~ Auto-generate experimental warnings and usage docs for HTTP typekits Mar 3, 2026

Copilot finished work on behalf of markcowl March 3, 2026 03:46

Copilot started work on behalf of markcowl March 3, 2026 03:46 View session

Merge latest main branch

27e2db9

Copilot finished work on behalf of markcowl March 3, 2026 03:49

Copilot started work on behalf of markcowl March 3, 2026 03:49 View session

markcowl requested changes Mar 5, 2026

View reviewed changes

Copilot started work on behalf of markcowl March 5, 2026 00:36 View session

Copilot AI and others added 2 commits March 5, 2026 00:37

Merge latest main

584f40f

Remove package-specific logic and skip usage instructions for compile…

843912c

…r typekits Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Copilot AI requested a review from markcowl March 5, 2026 00:50

Copilot finished work on behalf of markcowl March 5, 2026 00:50

markcowl requested changes Mar 5, 2026

View reviewed changes

packages/tspd/src/ref-doc/components/typekits-file.tsx Outdated Show resolved Hide resolved

Copilot started work on behalf of markcowl March 5, 2026 21:24 View session

Add usage instructions for compiler typekits with import statement

882add9

Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Copilot AI requested a review from markcowl March 5, 2026 21:35

Copilot finished work on behalf of markcowl March 5, 2026 21:35

markcowl requested changes Mar 5, 2026

View reviewed changes

Copilot started work on behalf of markcowl March 5, 2026 21:46 View session

Simplify logic and fix conditional rendering for experimental warning…

eeb575d

…s and usage docs Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Copilot AI requested a review from markcowl March 5, 2026 21:57

Copilot finished work on behalf of markcowl March 5, 2026 21:57

Copilot started work on behalf of markcowl March 9, 2026 20:07 View session

Merge branch 'main' of https://github.com/microsoft/typespec into cop…

a1b68fe

…ilot/fix-http-typekits-documentation

Copilot finished work on behalf of markcowl March 9, 2026 20:18

markcowl requested changes Mar 9, 2026

View reviewed changes

Copilot started work on behalf of markcowl March 9, 2026 23:14 View session

Simplify logic by extracting conditional text to variables

4717332

Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Copilot AI requested a review from markcowl March 9, 2026 23:29

Copilot finished work on behalf of markcowl March 9, 2026 23:29

Conversation

Copilot AI commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reproduction

Checklist

Comments on the Issue (you are @copilot in this section)

Uh oh!

markcowl commented Feb 24, 2026

Uh oh!

Copilot AI commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

markcowl commented Mar 3, 2026

Uh oh!

markcowl commented Mar 3, 2026

Uh oh!

Copilot AI commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

markcowl commented Mar 3, 2026

Uh oh!

Copilot AI commented Mar 3, 2026

Uh oh!

markcowl left a comment

Choose a reason for hiding this comment

Uh oh!

markcowl Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Uh oh!

Copilot AI commented Mar 5, 2026

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

markcowl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

markcowl commented Mar 9, 2026

Uh oh!

Copilot AI commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

markcowl Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Mar 9, 2026

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Feb 2, 2026 •

edited

Loading

Copilot AI commented Feb 24, 2026 •

edited

Loading

Copilot AI commented Mar 3, 2026 •

edited

Loading

Copilot AI commented Mar 5, 2026 •

edited

Loading

Copilot AI commented Mar 5, 2026 •

edited

Loading

Copilot AI commented Mar 9, 2026 •

edited

Loading